跳转到主要内容
通过标准协议推送自有系统告警事件到 Flashduty，实现告警事件自动化降噪处理。
Flashduty 已经适配了大部分常用告警系统的 webhook 协议，对于这些系统您应该首先使用对应的集成，更加简单方便。本集成提供了一个标准的 HTTP 接口，需要您开发适配。好处是您可以推送任何你想进行oncall的告警事件。

​
操作步骤

​
在 Flashduty

您可通过以下2种方式，获取一个集成推送地址，任选其一即可。
当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。
  1. 进入 Flashduty 控制台，选择 协作空间，进入某个空间的详情页面
  2. 选择 集成数据 tab，点击 添加一个集成，进入添加集成页面
  3. 选择 标准告警事件 集成，点击 保存，生成卡片。
  4. 点击生成的卡片，可以查看到 推送地址，复制备用，完成。
当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。
  1. 进入 Flashduty 控制台，选择 集成中心=>告警事件，进入集成选择页面。
  2. 选择 标准告警事件 集成：
    • 集成名称：为当前集成定义一个名称。
  3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 路由 进行更多路由规则的配置）。
  4. 点击 保存 后，复制当前页面的新生成的 推送地址 备用。
  5. 完成。

​
一、请求描述

​
请求方式

POST, Content-Type:“application/json”

​
请求参数：

​
Headers:

字段必含类型释义
Content-Type是string固定值：application/json。

​
Query Strings:

字段必含类型释义
integration_key是string集成秘钥，用于访问控制。添加集成后获得。

​
Payload:

字段必含类型释义
title_rule是string告警标题，不超过512个字符，超出后将自动截断。支持根据告警内容动态生成标题，生成规则请参考 定制故障标题。
event_status是string告警状态。枚举值（首字母大写）：Critical：严重，Warning：警告，Info：提醒，Ok：恢复。当指定为Ok时，意味着对告警进行自动恢复。
alert_key否string告警标识，用于对已经存在的告警进行更新或自动恢复。您可以自定义此值，但不可超过255个字符。您也可以依赖系统自动生成，该值会在响应中返回。如果您上报的是恢复事件，则此值必须存在。
description否string告警描述，不超过2048个字符，超出后将自动截断。
labels否map告警标签集合，key 为标签名称，value 为标签值。1. 标签的 key 和 value 均为 string 类型，区分大小写。2. 标签的 key 不要超过128个字符，遵循Prometheus标签命名规范。value 不超过2048个字符，超出后将自动截断。3. 至多传入50个标签。标签内容参考最佳实践。示例：“resource”: “171.26.23.22”, “check”: “api latency > 500ms”
images否[]image图片数组，可用于前端或飞书和钉钉应用通知的图片展示。系统根据 alt 进行合并覆盖，相同(包括空字符)的alt只保留一条

​
image 结构体

字段必含类型释义
alt否string图片的替代文本, 长度限制 128 字符，超长截断。
src是string图片来源，值：http/https 开头的图片链接地址 或 图片上传接口返回的image_key，长度限制 256 字符，超长会被丢弃
href否string超链接引用路径，长度限制 256 字符，超长截断

​
请求响应

字段名称必选类型描述
request_id是string请求 ID，用于链路追踪
error否Error错误描述，仅当出现错误时返回
data否Data上报信息
Data:
字段名称必选类型描述
alert_key否string告警标识，可依据此值上报恢复事件。如果您上报事件时，已经指定了 alert_key，则此值不变。否则，系统自动生成。
Error:
字段名称必选类型描述
code是string错误码，枚举值参考 Code
message否string错误描述
Code:
错误码HTTP Status描述
InvalidParameter400参数错误
InvalidContentType400Conten-Type 不支持
MethodNotAllowed400HTTP Method 不支持
Unauthorized401登录认证未通过
AccessDenied403权限认证未通过
RequestTooFrequently429请求过于频繁
RouteNotFound404请求 Method+Path 未匹配
ResourceNotFound400账户未购买资源，先前往费用中心线操作下单
NoLicense400账户无充足订阅 License，先前往费用中心升级或购买订阅
InternalError500内部或未知错误

​
二、请求示例

请求： 
curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_key}' \
-H 'Content-Type: application/json' \
-d '{
    "event_status": "Warning",
    "title_rule": "cpu idle low than 20%",
    "labels": {
        "service": "engine",
        "cluster":"nj",
        "resource":"es.nj.01",
        "check":"cpu.idle<20%",
        "metric":"node_cpu_seconds_total"
    }
}' -v
成功响应： 
{
    "request_id": "0ace00116215ab4ca0ec5244b8fc54b0",
    "data": {
        "alert_key": "9qJ798NJoXS4UMVB5SHsNj"
    }
}
失败响应： 
{
    "request_id": "0ace00116215abc0ba4e52449bd305b0",
    "error": {
        "code": "InvalidParameter",
        "message": "integration_key is not a valid one"
    }
}

​
三、最佳实践

  1. 当告警状态发生变更时，向 Flashduty发送事件
  2. 当告警恢复时，发送一个 status 为 Ok 的事件，来关闭告警。否则，告警将一直处于打开状态。如果您的告警系统没有恢复事件，建议您手动发送恢复事件
  3. 标签是事件的描述，应尽量丰富标签内容（发送时指定，或者通过配置 enrichment 规则来生成新的标签），比如：
    • 告警的发生来源，如 host，cluster，check 或 metric 等
    • 告警的归属信息，如 team，owner 等
    • 告警的类别信息，如 class（api，db，net）

​
四、常见问题

在 Flashduty
  1. 查看集成是否展示了 最新事件时间？如果没有，代表Flashduty没有收到推送，直接优先您的系统。
  2. 如果您使用的是 共享集成，优先确认您是否配置了 路由规则。不设置路由规则，系统会直接拒绝新的推送，因为没有协作空间可以承接您的告警。这种情况下，直接配置路由规则到您期望的空间即可。
在您的系统
  1. 确认您请求的地址，和集成详情中的地址完全一致。
  2. 确认您的服务可以访问外网 api.flashcat.cloud 域名。如果不可以，您首先需要为 server 开通外网，或单独针对 Flashduty 的域名开通外网访问。
  3. 打印 Flashduty 服务的响应结果，查看是否有明确信息。
如果以上步骤执行之后，仍然没有查询到问题根因，请 携带请求响应中的 request_id 联系我们。
Flashduty 使用2层降噪机制：
  1. 首先对告警event进行去重检查，如果您推送的event和之前推送的event内容完全一致，则新的event将被直接丢弃。
  2. 如果新的event的状态和描述和其对应的告警的上一条event的状态、标题、描述均一致，则新的event将被直接丢弃，同时更新归属告警属性。
  3. 新的event可能由于匹配到排除、丢弃、抑制或静默规则，而被丢弃。
  4. 当新的event触发了新告警，则系统会进入第二层降噪检查，判断新告警是否可以被合并到某个活跃的故障中，如果可以，则只会并入已有的故障，而不会产生新故障。
更多内容请参考 告警降噪。